{"swagger": "2.0", "basePath": "/soar-access", "paths": {"/cases/assign-user-case": {"post": {"responses": {"504": {"description": "The request encountered a timeout while waiting for an upstream action", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "404": {"description": "The Details provided are not found.", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "500": {"description": "An unexpected issue occurred on the server", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "403": {"description": "The caller is not authenticated or authorized to perform the action", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "400": {"description": "There was an issue with the request", "schema": {"$ref": "#/definitions/ResponseMessage"}}}, "summary": "Assign Specific user to a particular Case belonging to a company", "description": "The endpoint receives the user_id, case_id and global_comany_id, \nquerying the configured case management system to assign user to a designated case.\n\nPermissions Required (any):\n- EDIT_INCIDENTS\n- EDIT_CASES\n\nFeatures Required: N/A", "operationId": "external:AssignUserCase", "parameters": [{"name": "Authorization", "in": "header", "type": "string"}, {"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/AssignToUserCaseSchema"}}], "tags": ["cases"]}}, "/cases/case-infographic": {"post": {"responses": {"200": {"description": "Retrieved list of Case metrics", "schema": {"$ref": "#/definitions/CaseInfographicResponse"}}, "500": {"description": "An unexpected issue occurred on the server", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "504": {"description": "The request encountered a timeout while waiting for an upstream action", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "403": {"description": "The caller is not authenticated or authorized to perform the action", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "400": {"description": "There was an issue with the request", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "404": {"description": "The Details provided are not found.", "schema": {"$ref": "#/definitions/ResponseMessage"}}}, "summary": "Get a collection of different metrics based on a company's Cases", "description": "The endpoint is configured to receive a filter and the company's context. \nIt then queries the configured case management system, utilizing the resulting cases to populate a set of metrics \ncategorized by priority, status, OpenIncident, CaseTrend, and CaseTag.\n\nPermissions Required:\n- VIEW_CASE_METRICS\n\nFeatures Required: N/A", "operationId": "external:getCaseInfographic", "parameters": [{"name": "Authorization", "in": "header", "type": "string"}, {"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/GetCasesRequest"}}, {"name": "X-Fields", "in": "header", "type": "string", "format": "mask", "description": "An optional fields mask"}], "tags": ["cases"]}}, "/cases/case-metrics": {"post": {"responses": {"200": {"description": "Retrieved list of Case metrics", "schema": {"$ref": "#/definitions/CaseMetricsResponse"}}, "500": {"description": "An unexpected issue occurred on the server", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "504": {"description": "The request encountered a timeout while waiting for an upstream action", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "403": {"description": "The caller is not authenticated or authorized to perform the action", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "400": {"description": "There was an issue with the request", "schema": {"$ref": "#/definitions/ResponseMessage"}}}, "summary": "Get a collection of MTT'X' metrics based on a company's Cases", "description": "The endpoint is set up to filter data by days, accept a list of metric names, and consider the company's context. \nIt subsequently queries the SOAR BigQuery to fetch values for the following metrics:\n- MTTD (Mean Time to Detection)\n- MTTC (Mean Time to Contain)\n- MTTR (Mean Time to Recover)\n\nIt retrieves data only for the metrics listed in the input.\n\nPermissions Required:\n- VIEW_CASE_METRICS\n\nFeatures Required: N/A", "operationId": "external:getCaseMetrics", "parameters": [{"name": "Authorization", "in": "header", "type": "string"}, {"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/CaseMetricsCalculation"}}, {"name": "X-Fields", "in": "header", "type": "string", "format": "mask", "description": "An optional fields mask"}], "tags": ["cases"]}}, "/cases/close-case": {"post": {"responses": {"500": {"description": "An unexpected issue occurred on the server", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "504": {"description": "The request encountered a timeout while waiting for an upstream action", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "403": {"description": "The caller is not authenticated or authorized to perform the action", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "400": {"description": "There was an issue with the request", "schema": {"$ref": "#/definitions/ResponseMessage"}}}, "summary": "Change the status of the case to closed with a close reason and comment ", "description": "The endpoint receives company context and a list of case IDs to close, updating each to a \"closed\" state. \nAdditional details like close reason, root cause, and comments are recorded, with a 204 No Content response confirming successful closure.\nPermissions Required (any):\n- EDIT_INCIDENTS\n- EDIT_CASES\n\nFeatures Required: N/A", "operationId": "external:closeCase", "parameters": [{"name": "Authorization", "in": "header", "type": "string"}, {"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/closeCase"}}], "tags": ["cases"]}}, "/cases/get-case-activity-timeline/{case_id}": {"parameters": [{"in": "path", "description": "Unique identifier of the case", "name": "case_id", "required": true, "type": "string"}], "post": {"responses": {"200": {"description": "Retrieved the activity timeline details of a specific Case", "schema": {"$ref": "#/definitions/ActivityTimelineResponse"}}, "500": {"description": "An unexpected issue occurred on the server", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "504": {"description": "The request encountered a timeout while waiting for an upstream action", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "403": {"description": "The caller is not authenticated or authorized to perform the action", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "400": {"description": "There was an issue with the request", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "404": {"description": "The Details provided are not found.", "schema": {"$ref": "#/definitions/ResponseMessage"}}}, "summary": "Get the activity timeline details of a specific Case belonging to a company", "description": "The endpoint receives the company's context, \nquerying the configured case management system to retrieve specific activity timeline details of the designated case.\n\nPermissions Required (any):\n- VIEW_INCIDENTS\n- VIEW_CASES\n\nFeatures Required: N/A", "operationId": "external:getCaseActivityTimeline", "parameters": [{"name": "Authorization", "in": "header", "type": "string"}, {"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/GetCasesCompanyContext"}}, {"name": "X-Fields", "in": "header", "type": "string", "format": "mask", "description": "An optional fields mask"}], "tags": ["cases"]}}, "/cases/get-cases": {"post": {"responses": {"200": {"description": "Retrieved a list of Case cards", "schema": {"$ref": "#/definitions/CasesResponse"}}, "500": {"description": "An unexpected issue occurred on the server", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "504": {"description": "The request encountered a timeout while waiting for an upstream action", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "403": {"description": "The caller is not authenticated or authorized to perform the action", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "400": {"description": "There was an issue with the request", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "404": {"description": "The Details provided are not found.", "schema": {"$ref": "#/definitions/ResponseMessage"}}}, "summary": "Get a paginated list of a company's Cases", "description": "The endpoint receives a filter along with the company's context, \nquerying the configured case management system to retrieve a paginated list of cases related to that company.\n\nPermissions Required (any):\n- VIEW_INCIDENTS\n- VIEW_CASES\n\nFeatures Required: N/A", "operationId": "external:getCases", "parameters": [{"name": "Authorization", "in": "header", "type": "string"}, {"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/GetCasesRequest"}}, {"name": "X-Fields", "in": "header", "type": "string", "format": "mask", "description": "An optional fields mask"}], "tags": ["cases"]}}, "/cases/get-cases/{caseID}": {"parameters": [{"in": "path", "description": "Unique identifier of the case", "name": "caseID", "required": true, "type": "string"}], "post": {"responses": {"200": {"description": "Retrieved the details of a specific Case", "schema": {"$ref": "#/definitions/CaseResponse"}}, "500": {"description": "An unexpected issue occurred on the server", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "504": {"description": "The request encountered a timeout while waiting for an upstream action", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "403": {"description": "The caller is not authenticated or authorized to perform the action", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "400": {"description": "There was an issue with the request", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "404": {"description": "The Details provided are not found.", "schema": {"$ref": "#/definitions/ResponseMessage"}}}, "summary": "Get the details of a specific Case belonging to a company", "description": "The endpoint receives a filter along with the company's context, \nquerying the configured case management system to retrieve specific details of the designated case.\n\nPermissions Required (any):\n- VIEW_INCIDENTS\n- VIEW_CASES\n\nFeatures Required: N/A", "operationId": "external:getCase", "parameters": [{"name": "Authorization", "in": "header", "type": "string"}, {"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/GetCasesCompanyContext"}}, {"name": "X-Fields", "in": "header", "type": "string", "format": "mask", "description": "An optional fields mask"}], "tags": ["cases"]}}, "/cases/get-root-cause": {"post": {"responses": {"200": {"description": "Retrieved a list of root causes", "schema": {"$ref": "#/definitions/RootCauseResponse"}}, "500": {"description": "An unexpected issue occurred on the server", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "504": {"description": "The request encountered a timeout while waiting for an upstream action", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "403": {"description": "The caller is not authenticated or authorized to perform the action", "schema": {"$ref": "#/definitions/ResponseMessage"}}, "400": {"description": "There was an issue with the request", "schema": {"$ref": "#/definitions/ResponseMessage"}}}, "summary": "Get the root causes based on the Closure Reason from SOAR", "description": "The endpoint to return the list of root cause configured in the system. \nPermissions Required (any):\n- VIEW_INCIDENTS\n- VIEW_CASES\n\nFeatures Required: N/A", "operationId": "external:getRootCause", "parameters": [{"name": "Authorization", "in": "header", "type": "string"}, {"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/CompanyContext"}}, {"name": "X-Fields", "in": "header", "type": "string", "format": "mask", "description": "An optional fields mask"}], "tags": ["cases"]}}, "/health/": {"get": {"responses": {"200": {"description": "Success"}}, "summary": "Check the status of the application", "description": "Permissions Required: N/A\n\nFeatures Required: N/A", "operationId": "external:getHealth", "parameters": [{"name": "Authorization", "in": "header", "type": "string"}], "tags": ["health"]}}}, "info": {"title": "SOAR Access Service", "version": "1.0.1-alpha", "description": "REST API for retrieving and managing Cases in Chronicle SOAR"}, "produces": ["application/json"], "consumes": ["application/json"], "securityDefinitions": {"Bearer": {"type": "apiKey", "in": "header", "name": "Authorization"}}, "security": [{"Bearer": []}], "tags": [{"name": "health", "description": "Application health operations"}, {"name": "cases", "description": "SOAR Case operations"}], "definitions": {"GetCasesRequest": {"allOf": [{"$ref": "#/definitions/GetCasesCompanyContext"}, {"properties": {"filter": {"description": "Instructions on filtering, sorting, and paginating cases", "allOf": [{"$ref": "#/definitions/CasesRequest"}]}}, "type": "object"}]}, "GetCasesCompanyContext": {"required": ["company_context"], "properties": {"company_context": {"$ref": "#/definitions/CompanyContext"}}, "type": "object"}, "CompanyContext": {"required": ["global_company_id"], "properties": {"global_company_id": {"type": "string", "description": "Unique identifier of the global company for the cases request", "example": "set_this_value"}}, "type": "object"}, "CasesRequest": {"properties": {"sortType": {"type": "integer", "description": "Provide the sort type: ", "example": "1"}, "filterOperator": {"type": "integer", "description": "Provide the filter operator: ", "example": "0"}, "filters": {"type": "array", "items": {"$ref": "#/definitions/CasesFilter"}}, "startTime": {"type": "integer", "description": "Start time for filtering cases in Unix format, in milliseconds", "example": "0"}, "endTime": {"type": "integer", "description": "End time for filtering cases in Unix format, in milliseconds", "example": "0"}, "statuses": {"type": "array", "description": "Provide the status value: ", "example": "[1,5]", "items": {"type": "integer"}}, "isVisibleInQueue": {"type": "boolean", "description": "Retrieve cases that are currently visible in the queue", "example": "false"}, "timeRangeFilter": {"type": "integer", "description": "Provide the timeframe to review the cases: ", "example": 7}, "requestedPage": {"type": "integer", "description": "Number of pages containing cases to retrieve", "default": 0, "example": "0", "minimum": 0}, "pageSize": {"type": "integer", "description": "Number of cases per page", "default": 5, "example": "5", "minimum": 1}, "searchTerm": {"type": "string", "description": "Search term for cases", "example": "failed"}}, "type": "object"}, "CasesFilter": {"properties": {"type": {"type": "integer", "description": "Provide the type of the case in the queue: ", "example": "0"}, "operator": {"type": "integer", "description": "Provide the filter operator: ", "example": "1"}, "key": {"type": "string", "description": "Represents the case filter key", "example": "priority"}, "values": {"type": "array", "example": ["value"], "items": {"type": "string"}}, "includeUsers": {"type": "boolean", "description": "Determine if users should be included in the filter", "example": "true"}}, "type": "object"}, "CasesResponse": {"allOf": [{"$ref": "#/definitions/ResponseMessage"}, {"properties": {"caseCards": {"type": "array", "items": {"$ref": "#/definitions/CasesListCaseCard"}}, "paging": {"$ref": "#/definitions/Paging"}}, "type": "object"}]}, "ResponseMessage": {"properties": {"message": {"type": "string", "description": "Error message", "readOnly": true}}, "type": "object"}, "CasesListCaseCard": {"properties": {"id": {"type": "integer", "description": "Unique identifier of the case card", "readOnly": true}, "creationTimeUnixTimeInMs": {"type": "integer", "description": "The creation time of the case in Unix format, in milliseconds"}, "modificationTimeUnixTimeInMs": {"type": "integer", "description": "The time of modification of the case in Unix format, in milliseconds"}, "title": {"type": "string", "description": "Title of the case card"}, "isIncident": {"type": "boolean", "description": "Indicates that the case card is depicted as an incident"}, "environment": {"description": "Current environment for the case card", "allOf": [{"$ref": "#/definitions/CasesListCaseCardEnvironment"}]}, "priority": {"type": "integer", "description": "Provide the priority of the case: "}, "assignedUserName": {"type": "string", "description": "Username associated with the case card"}, "status": {"type": "integer", "description": "Provide the status of the case: "}}, "type": "object"}, "CasesListCaseCardEnvironment": {"properties": {"name": {"type": "string", "description": "Name of the environment"}}, "type": "object"}, "Paging": {"properties": {"pageSize": {"type": "integer", "description": "Number of cases per page", "example": 5}, "requestedPage": {"type": "integer", "description": "Specific page number of cases", "example": 0}, "totalCount": {"type": "integer", "description": "Total number of cases", "example": 6}}, "type": "object"}, "CaseResponse": {"allOf": [{"$ref": "#/definitions/ResponseMessage"}, {"properties": {"case": {"$ref": "#/definitions/CaseDetail"}}, "type": "object"}]}, "CaseDetail": {"properties": {"id": {"type": "integer", "description": "Unique identifier of the case", "readOnly": true}, "priority": {"type": "integer", "description": "Provides the priority of the case: "}, "assignedUser": {"type": "string", "description": "User assigned for the case"}, "environment": {"type": "string", "description": "Case environment"}, "status": {"type": "integer", "description": "Provides the status of the case: "}, "name": {"type": "string", "description": "Title of the case"}, "creationTimeUnixTimeInMs": {"type": "integer", "description": "The creation time of the case in Unix format, in milliseconds"}, "modificationTimeUnixTimeInMs": {"type": "integer", "description": "The time of modification of the case in Unix format, in milliseconds"}, "stage": {"type": "string", "description": "Case stage"}, "tags": {"type": "array", "description": "List of case tags", "items": {"type": "string"}}, "description": {"type": "string", "description": "Case description"}, "alertCards": {"type": "array", "description": "List of alert cards", "items": {"$ref": "#/definitions/AlertCard"}}, "assignedUserDetails": {"$ref": "#/definitions/UserDetail"}}, "type": "object"}, "AlertCard": {"properties": {"id": {"type": "integer", "description": "Unique identifier of the alert", "readOnly": true}, "creationTimeUnixTimeInMs": {"type": "integer", "description": "Alert ingestion time in Unix format, in milliseconds"}, "modificationTimeUnixTimeInMs": {"type": "integer", "description": "Alert modification time in Unix format, in milliseconds"}, "identifier": {"type": "string", "description": "Represents the unique alert identifier (alertName + ticketId)"}, "status": {"type": "integer", "description": "Provide the status of the alert: "}, "priority": {"type": "integer", "description": "Provide the priority of the case: "}, "workflowsStatus": {"type": "integer", "description": "Provide the status of a playbook execution"}, "title": {"type": "string", "description": "Alert display name"}, "startTime": {"type": "integer", "description": "Start time for the first alert event in Unix format, in milliseconds"}, "endTime": {"type": "integer", "description": "End time for the last alert event in Unix format, in milliseconds"}, "name": {"type": "string", "description": "Alert display name"}, "sourceUrl": {"type": "string", "description": "Configured source url - defined in the connector that ingested this alert"}}, "type": "object"}, "UserDetail": {"properties": {"firstName": {"type": "string", "description": "First name of user"}, "lastName": {"type": "string", "description": "Last name of user"}, "email": {"type": "string", "description": "Email of user"}}, "type": "object"}, "CaseInfographicResponse": {"allOf": [{"$ref": "#/definitions/ResponseMessage"}, {"properties": {"Priority": {"type": "array", "description": "Metrics based on Case priority", "items": {"$ref": "#/definitions/CaseMetricsPriority"}}, "Status": {"type": "array", "description": "Metrics based on Case status", "items": {"$ref": "#/definitions/CaseMetricsStatus"}}, "OpenIncident": {"type": "string", "description": "Number of Cases open as Incident", "example": "37"}, "CaseTrend": {"type": "array", "description": "Number of cases by priority for a specific date", "items": {"$ref": "#/definitions/CaseMetricsCaseTrend"}}, "CaseTag": {"type": "array", "description": "Number of cases by Tag for a specific date", "items": {"$ref": "#/definitions/CaseMetricsCaseTagTrends"}}}, "type": "object"}]}, "CaseMetricsPriority": {"properties": {"priority": {"type": "integer", "description": "Priority level", "example": 40}, "value": {"type": "integer", "description": "Number of cases for this priority level", "example": 212}}, "type": "object"}, "CaseMetricsStatus": {"properties": {"status": {"type": "integer", "description": "Status indicator", "example": "1"}, "value": {"type": "integer", "description": "Number of cases for this status indicator", "example": "6"}}, "type": "object"}, "CaseMetricsCaseTrend": {"properties": {"Date": {"type": "string", "description": "Specific date for the current metrics in the format DD-MM-YYYY", "example": "04-12-2024"}, "*": {"type": "object", "description": "The count of associated cases for each priority", "example": "100", "additionalProperties": {"type": "integer"}}}, "type": "object"}, "CaseMetricsCaseTagTrends": {"properties": {"Tag": {"type": "string", "description": "Tag corresponding to the current metrics"}, "*": {"type": "object", "description": "The count of associated cases for each priority", "example": "100", "additionalProperties": {"type": "integer"}}}, "type": "object"}, "CaseMetricsCalculation": {"properties": {"company_context": {"$ref": "#/definitions/CompanyContext"}, "filter_by_days": {"type": "integer", "description": "The metric calculation will be performed for the specified previous days", "example": 100}, "metric_name": {"type": "array", "description": "Consists of list of metrics, the metrics currently included are 'MTTD', 'MTTC' and 'MTTR'", "example": ["MTTD", "MTTR", "MTTC"], "items": {"type": "string"}}}, "type": "object"}, "CaseMetricsResponse": {"allOf": [{"$ref": "#/definitions/ResponseMessage"}, {"properties": {"MTTD": {"type": "array", "description": "Gives the value of Mean Time to Detection for Security Alerts in hours", "example": [1.256], "items": {"type": "number"}}, "MTTC": {"type": "array", "description": "Gives the value of Mean Time to Contain for Security Alerts in hours", "example": [1.356], "items": {"type": "number"}}, "MTTR": {"type": "array", "description": "Gives the value of Mean Time to Recover for Security Alerts in hours", "example": [1.456], "items": {"type": "number"}}}, "type": "object"}]}, "ActivityTimelineResponse": {"allOf": [{"$ref": "#/definitions/ResponseMessage"}, {"properties": {"caseActivityTimeline": {"type": "object", "description": "ActivityTimeline case details"}}, "type": "object"}]}, "AssignToUserCaseSchema": {"required": ["case_id", "company_context", "user_email"], "properties": {"company_context": {"$ref": "#/definitions/CompanyContext"}, "user_email": {"type": "string", "description": "User mail address", "example": "abc@example.com"}, "case_id": {"type": "integer", "description": "Unique identifier of the case", "example": "1234"}}, "type": "object"}, "RootCauseResponse": {"properties": {"root_cause_records": {"type": "array", "description": "List of close reasons, each with associated root causes", "items": {"$ref": "#/definitions/CloseReason"}}}, "type": "object"}, "CloseReason": {"properties": {"close_reason": {"type": "integer", "description": "The reason for closing the case, represented as an enum: "}, "root_causes": {"type": "array", "description": "List of root causes associated with the close reason", "items": {"$ref": "#/definitions/RootCause"}}}, "type": "object"}, "RootCause": {"properties": {"id": {"type": "integer", "description": "Unique identifier for the root cause", "readOnly": true}, "root_cause": {"type": "string", "description": "Description of the root cause", "maxLength": 300}}, "type": "object"}, "closeCase": {"required": ["close_status", "company_context"], "properties": {"company_context": {"$ref": "#/definitions/CompanyContext"}, "close_status": {"$ref": "#/definitions/closeStatus"}}, "type": "object"}, "closeStatus": {"required": ["caseId", "closeReason", "rootCause"], "properties": {"caseId": {"type": "integer", "description": "Unique identifier of the case", "example": 321}, "closeReason": {"type": "integer", "description": "The reason for closing the case, represented as an enum: ", "example": "1"}, "rootCause": {"type": "string", "description": "Root cause for closing the case", "example": "External attack"}, "closeComment": {"type": "string", "description": "Comments to describe the change of status", "example": "Fixed"}}, "type": "object"}}, "responses": {"ParseError": {"description": "When a mask can't be parsed"}, "MaskError": {"description": "When any error occurs on mask"}}}